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2.0 Design Goals 
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3.0 PILOT Operating Modes 

PILOT is always in one of three operating modes, either 
immediate mode, run mode or auto-number input mode. In 
immediate mode, the interpreter reads and executes command lines 
from the Screen Editor; while in run mode, the interpreter 
executes a program from the deferred program storage area; and 
while in auto-number input mode, the interpreter reads PILOT 
statements from the Screen Editor and saves them for deferred 
execution. 


3.1 Immediate Mode 

The system initializes to immediate mode and signals that it is 
ready to accept a PILOT input line by issuing a prompt message 
'READY' to the screen and displaying a visible cursor (white 
box) at the beginning of the following line. The operator then 
has three choices: either enter a PILOT statement for immediate 
execution, enter a PILOT statement for deferred execution, or 
delete a deferred PILOT statement. The mechanism for making the 
choice is an optional line number at the beginning of the input 
line, as shown below: 

T:HELLO Immediate execution (no line number). 

300 T:HELLO Deferred execution (line number). 

200 Delete line 100 (no statement). 

The system remains in immediate mode until one of the commands 
shown below is entered for immediate execution, at whic - ' time 
the system changes mode. 


Command 


New mode 


Run 

Jump 

End 

Use 

Auto-number 

Dos 


Run 

Run 

Run 

Run 

Auto-number 

Leaves PILOT environment 


3.2 Run Mode 

In run mode the PILOT interpreter is executing the program 
residing in the program storage area; the program will execute 
until one of the following conditions occurs: 

The operator presses the BREAK key (preferred to RESET because 
BREAK produces an orderly stop) . 

The operator presses the RESET key (potentially dangerous 
because PILOT could be in the process of altering the string 
variable list; the interruption would leave the list in an 
unusable state) . 

The program runs out of statements to execute. 
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3.3 Auto-number Input Mode 

In auto-number input mode, the PILOT interpreter is reading 
PILOT statements from the Screen Editor, syntax checking the 
statements, and if correct then appending an internally 
generated line number and storing the statement in the program 
storage area. When a totally blank line is input by the 
operator, or if an invalid line number is generated, PILOT 
returns to immediate mode. 


ATiON, REVISION e. -- z/-OCt-bk)) 


in the program with the Use 
ion technique) . 


such as 

a j 

ump 

to a non- 

xecut ion 

due 

to 

one of 

the 

11 retur 

n to 

immed iate 

mode . 


enerated to indicate why. See 
differences between these 




- 6 - 


i'iLUi L Ai. L 


ui Lvi [ lLniiUh', iv Hi V To 1 U W 


L 


Z / ~ wU L ~ C u > 


4.0 PILOT General Statement Syntax 

Ihe syntax specifications contained in the body of this document 
are similar to BNF , except that square bracket pairs "[ ... ]" 
are used to delimit optional fields. 

<PI LOT input 1 ine> : := [<line #>][<PILOT statement ] <EOL> 

<line #> ::= <numeric constant> 

<PILOT statement> : := [ <label> ] [<command> ] [<comment> ] 

<label> : := *<label name> 

<label name> ::= <a lphanumer ic character> [ <label name)] 

<command> :: = ( <command name) ] [<condition> ] : [Ccommand 

parameters> ] 

<command name) ::= A | T | M | C | J | U | E | R | Y | N | RUN | LIST | DUMP | NEW | VNEW | 

READ | WRITE | CLOSE | MS | JM | GR | SO | PA | POS | CAVSS | 

LOAD | SAVE | DOS |T§ YNC | AUTO | REN | TRACE 
<condition> :; = [ Y | N] [ ( <nexp> ) ] 

(command parameters) : := as defined for each command in Section 6. 
(comment) ::= {<any character other than EOL> 

<EOL> ::= <end-of-line character (9B hex) supplied by the 

Screen Editor on every line.> 

Some examples of PILOT input lines with valid syntax follow: 

100 T: HELLO, HOW ARE YOU TODAY? 

20 A: 

30 

8000 *START 
T: HELLO THERE. 

160 : 

999 *LOOP C:#A=#A+1 [ INCREMENT THE LOOP COUNT. 

84 TY : VERY GOOD! 

60 J (#A>1 ) : *MORE 

Ihe elements of a PILOT input line are described in the 
following paragraphs: 


4.1 Line Number 

The optional line number must be within the range of 0 to 9999, 
when entered. 


4.2 Statement Label 

The statement label may be of any length (as governed by the 
longest input line allowed) and all characters in the label are 
significant and are retained. There is no test made for 
duplicate labels; if there are two statements with identical 
labels, the one with the lower line number will be the target of 

Jump and use commands. The label is delimited by the first non- 
alphanumeric character found. 


4.3 PI jOT Command 
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The PILOT command must be spelled precisely as there are no 
short forms or long forms supported. For example: "TYPEN:" 
would be interpreted as TY<junk>: rather than T< ignor ed>N : . 
Atari PILOT commands are specified in Section 6. 


4.4 Condition 

The optional condition field allows for the selective execution 
of any and all PILOT statements. There are two criteria for the 
selection: the Match result flag tests, Y and N, and/or the 
arithmetic test ( <numeric expression ). When both tests 
are part of the condition, both must be true for the statement 

to execute. 

If Y is the condition, the statement is executed only if the 
most recent Match command found a match; conversely, if N is the 
condition, the statement is executed if the most recent Match 

command did not find a match* 

For the arithmetic test, if the expression within parens has a 
value greater than zero, the statement is executed; if the value 
is less than or equal to zero, the statement is not executed. 


4.5 Field Delimiting 

All Helds are delimited by the first occurrence of a character 
whim is not valid for that field. For example, the line number 
fie d is delimited by the first non-numeric character, which may 
be Hut is not required to be) a blank. Blanks are ignored to 
the left of the except to delimit fields, so they may be 

used liberally to format a PILOT input line; note, however, that 
in deferred execution statements, the blanks do use up storage 
space (one byte per blank). Some examples of valid input lines 

(without and without blanks) are shown below: 

1 00T :THIS IS VALID. 

1 00*LOOP A: 

100J( #1 - 3) : *LOOP 
100 J (#1-3) : *LOOP 

The comma is a general purpose operand delimiter (to the right 
of the ':') and commas and blanks may be used interchangeably 
in that context. Note that any consecutive string of commas 
and/or blanks is treated as a single separator, except within 
the Match commands. 


<sep> : := <space> I , I <sep><sep> 


For example 


the statements shown below are all 


equivalent : 


LIST : 1 00 200 

LIST : 1 00 , 20 0 

LIST: 100 200 

LIST: 100, , , , ,,, #,200 


Single space as 
Single comma as 
Multiple spaces 
Multiple commas 


separator . 
separator . 
as separator, 
and spaces. 
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4.6 Comment 


The 

the 

EOL 


optional statement comment is delimited at 
square left bracket character (•[•) and at 
character; any character may appear inside 


the beginning by 
the end by the 
a comment. 


4.7 Command Continuation 


"continuation" iJ h%h° yEt d ° scribed - that is command 
are nwflf™ IhL ” h ’ ch the command name and condition result 

specified n, „! recently seen statement. This option is 
pecitied by having the command name and condition field both 

absent from the statement, as shown in the examples below* 


1 00 T(#A>40) : 

105 : THE RESULT IS TOO LARGE. 
110 : PLEASE TRY AGAIN. 


which is equivalent to: 


1 00 T ( #A> 4 0 ) : 

105 T ( #A> 4 0 ) : THE RESULT IS TOO LARGE 
310 T(#A>40) rPLEASE TRY AGAIN. 


Continuation is all owed only after 
and the Remark command when in run 
any other command will result in a 
stop the execution of the offending 
allowed after any command when in i 


the Type commands (T, Y & N) 
mode; a continuation after 
run-time error, which will 
program. Continuation is 
mmediate mode. 


ihe default continuation comnu.r 
default is also established aft 
RESET, an error of any kind and 
immediate mode. 


d at power-up is 
er the following 
transition from 


Type; that same 
conditions : 
run mode to 
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5.0 PILOT Data Types 

PILOT allows the user to manipulate two distinct types of data: 
numeric data and text data. 


5.1 Numeric Data 

Numeric data is maintained internally as 16-bit signed integers 
with a range of -32768 to +32767. All operations upon numeric 
data will produce integer results, truncated to 16 bits, with 
numbers in the range of 32768 to 65535 being treated as negative 
numbers in the range -32768 to -1 (standard two's complement 
arithmetic). A result of this convention is that the positive 
number domain wraps into the negative number domain, e.g. 32767 
+ 1 = -32768. Note that this is not considered an error by 
PILOT. 

The specifications for language elements that represent numeric 
data of various types given below: 


5.1.1 Numeric Constants — Numeric constants consist of one or 
more numeric digits, terminated by any non-numeric character. 
Numbers may have any (non-zero) number of digits, with the 
resultant value being truncated to a 16-bit signed number. In 
most, but not all, contexts a unary minus sign is allowed to 
precede the first digit. 

Cnumeric constant> : := [-] [<numeric constant> ] <digit> 
Examples : 

1 

32767 

00000000000023 

345698765243621864 

-475 


5.1.2 Numeric Variables — Numeric variables are specified by 
the prefix delimiter '#' followed by one of the letters 'A' 
through 'Z'. There are 26 numeric variables that can be 
accessed by the language, #A through fZ. 

Cnumeric variable> : := #<alphabetic character> 

Examples : 

#L 


5.1.3 Random Number -- A hardware generated random number may be 
used anywhere a numeric expression is allowed; the '?' character 
is used to specify that a random value is to be selected. 
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Examples : 


J (?) : *SOMETIMES 

Toss of the 

C : 1 A=? 

#A takes on 

GR:TIJRN ? 

Rotate theta 


coin Jump, 
a random value, 
by random amount. 


5.1.4 Atari Controller Sense -- The Atari paddle controllers, 
joysticks, lightpen and their associated trigger inputs may be 
sensed as numeric data using the following constructs: 

< joystick sense> : := %J<select> 

<paddle sense> : := %P<select> 

Ctrigger sense> ::= %T<select> 

<lightpen sense> ::= %H | %V | %L 

<select> ::= <number constant> | <numer ic var iable> | <pointer> 

The sense constructs are recognized anywhere a numeric constant 
is allowed and in text expressions. See Appendix F for more 
information regarding the controllers and the sense values. 

Examples : 


J 

C 

C 

C 


%T0 ) : *TRIGGER 

Jump 

if trigger set. 

#A=%P1 

Read 

Paddle #1 to numeri 

#J = %J#I 

Read 

Joystick specified 

#H = %H 

Read 

lightpen horizontal 


c variable 
by #1. 
value . 


# 


5.1.5 Special Variables — In addition to the controller sense 
variables, there are several other special "read only" variables 
which may be sensed (as if numeric constants) using the 
following constructs: 


<free memory> : := %F 
<graphics x-coordinate> 
<graphics y-coordinate> 
<graphics theta angle> 
<graphics data value> : 
<Match result> : := %M 


: := %X 
: : = %Y 
:= %A 
= %Z 


See section 6.1.12 


See section 6.1.4 


The special variables are recognized anywhere a numeric constant 
is allowed and in text expressions. 


Examples : 

T : FREE MEMORY = %F. 
J ( %M=5 ) : *CASE5 
GR : GOTO #X,%Y 
J ( %X>=8 0 ) : *OUTX 


\ 

Displays the amount of unused memory. 
Jump on Match result. 

Goto computed x, without changing y. 
Test for graphics cursor out window. 


5.1.6 Pointer -- A pointer is the specification of the memory 
address of a numeric quantity, the data at the specified address 
being one or two bytes in length. A pointer may be used 
anywhere a numeric variable is allowed. 
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The syntax for the pointer specification is shown below: 


<word pointer> ::= @<address> 

<byte pointer> ::= @B<address> 

<address> ::= <numeric constant> | <numer ic var iable> I <word pointer> 

The ’B’ is an optional modifier which specifies that the pointer 
points to a memory byte. If the ’B* is not present the pointer 
is assumed to point to the l.s.b. of a two-byte word, where the 
next higher memory location contains the m.s.b. of that word. 

The 6502 has no inherent word organization, so words may start 
on either even or odd addresses. 


In a multi-level indirect pointer reference the ’B’, if present, 
may only be placed at the outermost level, as shown below: 


C:#A = @B@4 096 is valid. 

C:#A = 00B4096 is not valid. 


(& 4097) = 5000 
(& 5001) = 4103 
(& 4104) = 5160 

4096. 

5000. 

5160. 


Examples : 


Content 

of 

location 

40 

96 

Content 

of 

location 

50 

00 

Content 

of 

location 

41 

03 

C:#A = 

409 

6 

# A 

=r 

C:£A = 

04096 

#A 

— 

C:#A = 

004 

096 

# A 

= 

C:#A = 

0B4 

096 

# A 

— 

C : #A = 

0B4 

097 

# A 





No 

t< 


136 (lsb of value 5000). 

19 (msb of value 5000). 

that 5000 = (1 9 * 256) + 136. 


The PILOT equivalents of the BASIC PEEK function and POKE 
command are shown below: 


PEEK (<addr>) @B<addr> 

POKE <addr > , <data> C:0B<addr> = <data> 

Since the internal storage for all numeric quantities within 
PILOT is as v/ord quantities, the following transformations will 
occur when byte pointers are used: 

Byte value as target -- the l.s.b. of the integer source value 
is stored and the m.s.b. is not used. The next higher memory 
byte above the byte target is neither accessed nor altered. 

Byte value as source -- the l.s.b. of the integer result is 
set to the value of the referenced byte and the m.s.b. of the 
integer result is set to zero. The next higher memory byte 
above the byte source is not accessed. 

When a pointer is used as a target for a numeric assignment, the 
byte or word is always read before it is written to; this may 
cause problems when writing to some types of hardware devices, 

such as a PIA, where the hidden read may clear a status bit 
before it is read by the program. 
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5.1 . 7 Numeric Expression -- A numeric expression (<nexp>) is a 
of °ne or more numeric elements separated by numeric or 
logicai orators, as in an algebraic formula. Numeric 
expressions are evaluated from left to right, with no operator 

eith2r e 2larifi e thp P f r0ntl i ’ eSeS are allowed (encouraged?) to 
eitner clarify the formulae or to alter the left to riqht 

evaluation scheme. Any number of redundant parens are allowed 

(those that don t alter the evaluation order) and up to 2 levels 

of nested non-redundant parens are allowed. 

<nexp> : := <operand> f <oper ator > <nexp> ] | (<nexp>) |-<nexD> 

<operand> ::= <numeric constant> | <numer i c variable>|?| 

<pointer> | <cont roller sense> | <special variable> 
<operator> :: = + I - I * | / 1 \ I > I < | = | <= | >= I <> 


The 

ope 

rato 

rs have t 

+ 

i s 

the 

numer i c 

— 

is 

the 

numeric 

* 

i s 

the 

numeric 

/ 

is 

the 

numer i c 


opposed to the 

\ 

i s 

the 

modulus 

The 

relational opera 

compare 

the 

term on 


generate a boolean r 
comparison. A value 
true, E when false. 


add i 
subt 
mult 
divi 
f loo 
oper 

tors 

thei 

esul 

of 


tion operator, 
raction operator, 
iplication operator. 

sion operator (truncated result, as 

r value or rounded result) . 

ator (result is always positive). 

^ — V\ov). — » 

all have the characteristic that they 
r left with the term on their right and 
t based upon the results of the 
1 is generated when the comparison is 


< 

< = 
> = 
<> 


is the "greater than" operator (test for left greater than 
right). 

„^ ess t ^ an " operator (test for left less than riqht) 

* s the e< 3 ua -*- to " operator (test for left equal to right). 

is tne less than or equal to" operator (left not greater 
than r lght) . 

is the "greater than or equal to" operator (left not less 
than right) . 

is the unequal to" operator (test for left not equal to 
right) . 


Examples : 


56 

#A+4 

( ( ( (7) ) ) ) 

1 + (1 4 2/ ( # J/ 6 ) ) 
1+2+3+4+5+6+7+8+9 
(1+2+3+4+5+6+7+8+9) 
#J/-3 
# V< 3 

(#A<3) * ( #B = #C ) 

( #D<>5) + ( #Z/2=1 ) 

@ #P> %F 


Extra (redundant) parens don't matter. 


Logical "and" of two relations. 
Logical "or" of two relations. 


5.2 Text Bata 
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Text data comes in two flavors, text literals and named strings. 
Unlike most languages, PILOT does not require quotes or any 
other kinds of delimiters for text literals; within the command 
context, anything that cannot be identified as being otherwise 
is assumed to be a text literal. 



5.2.1 Text Literal -- All textual data that is not explicitly 
identified as being otherwise, is assumed to be a text literal. 

Text literals may contain any ATASCII character except for the 
following : 

5 — this is the string variable name prefix delimiter. * 

# -- this is the numeric variable name prefix delimiter. * 

% -- this is the controller sense/special variable prefix 
delimiter. * 

@ -- this is the pointer specifier. * 

[ -- this is the comment prefix delimiter. 

<EOL> — this is the end of line delimiter. 

* Note: these characters may be used as literals if the 
character that follows does not start a valid data variable 
specification; a space is always suitable for this purpose. 

Some other possibilities are shown below: 

T:YOUR WEIGHT IS 30#. the makes the literal. 

T:#X%, ARE YOU SURE? the makes the literal. 

T:THE COST IS $#V. the makes the '$' literal. 

See Appendix G, item 11 for a further discussion of using and 

generating key words in text expression:. 

Examples : 

HERE IS SOME TEXT 

THIS & THAT. AND SOME MORE. 

% • |. +@????? 

BLANKS ARE SIGNIFICANT TOO! 


5.2.2 Named Strings -- A named string is a dynamic data element 
that consists of a name portion and a data portion. Just as a 
numeric variable has both a name (#A) and a value (-45), a 
string variable has a name ( $B IRTHPLACE) and a value (SAN JOSE); 
however, for a string variable, both the name and value are 
text. A string variable name consists of the prefix delimiter 
followed by at least one alphanumeric character (but up to 
254 total) . All characters in the string name have significance 
and are retained. String variable data consists of a single 
text literal of from zero (null string) characters up to 254 
ATASCII characters. The data portion never includes an <EOL> 
character . 

<string variable name> ::= $<alphanumeric character> 

[<alphanumer ic characters)*] 

Examples : 


- 14 - 


IflittKj. tiLvx LAi'bKWAL biXUl 


xLrviiUN, REVISION E 


x. / -uc L- d n 


$NAME 
5RESP0NSE 
$SIRTHPLACE 
$S1 
$6 
$ A 


5.2.3 Text Expression -- A text expression is a list of one or 
more textual elements which are concatenated to form a textual 
result. A text expression is scanned from left to right, with 
all data assumed to be literal text unless it is first delimited 
by '%' or * @ * in which case it is then assumed to be a 

.numeric variable (if a string variable (if '$'), a 

controller sense or special variable (if '%') or a numeric 
pointer (if * @ * ) . If a string variable is undefined, its name 
is substituted for the missing value. At the end of a variable 
name, scanning resumes assuming literal text once again. An 
optional underscore ('_'), if present as the last character of 
the text expression, will be converted to a blank as part of the 
evaluation of the text expression; this features allows trailing 
blank(s) to be part of text expressions, which the Atari Screen 
Editor would otherwise not allow. 

<texp> ::= Coper and> [ <texp> ] [_] 

<operand> ::= Ctext 1 iteral> | Cstr ing var iable> | Cnumer ic 

var iable> | Ccontrol ler sense> | especial variable>| 
<pointer> 

Examples : 

THIS IS TEXT 

HELLO $NAME 

YOUR AGE IS # A . 

HERE IS A TRAILING BLANK_ 

FREE MEMORY IS NOW %F BYTES. 

THE VALUE IS @5000. 

Text expression are evaluated into an internal buffer before 
being used as data for a PILOT command; the buffer size is 254 
characters and if a text expression exceeds that size it is 
truncated without a warning message or error being generated. 


5.2.4 String Indirection -- String indirection is a special 
syntactic form in which the data portion of one string is made 
to specify the name of another string. Just as the value of 
text literal ABC is 'ABC', and the value of $ABC is the data 
portion of the string named ABC, so the value of $$ABC is the 
data portion of the string whose name is the data portion of the 
string named ABC. As many '$'s as desired may precede the name 
portion, and this form may be used wherever a string variable is 
allowed. If the indirection cannot be carried to the number of 
specified levels, because of undefined string names, the result 
will be the same as that obtained by specifying a simple 
undefined string name. The examples below may clarify string 
indirection: 
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$LADDER=JANE existing named strings. 

$ JANE=ATARI 

$ATARI=LUNCH 


T : $LADDER 
T : $$LADDER 
T : $$ $LADDER 
T : $$$$LADDER 


will produce 
will produce 
will produce 
will produce 


’JANE' . 
'ATARI ' . 
'LUNCH' . 

' $LUNCH ' . 


Note that '$'s are not expected to be part of the string data in 
order to do indirection; in fact, if they are present, they will 
cause the indirection to fail, as they are not valid characters 
in a string name. In other words, all indirection is specified 
at the outer (command) level; no additional indirection is 
obtained via '$'s in the strings being scanned. 


String indirection is allowed anywhere a simple string variable 
is allowed. See Appendix G, item 3 for one possible use for 
string indirection. 


5.3 Explicit Delimiting 

Note that there may be up to four separate PILOT entities based 
upon a single alphabetic letter, let us use the letter 'F' for 
an example: 

F -- the text literal 
#F -- the numeric variable 
$F -- th t string variable 
*F -- th : statement label 

The PILOT system will not be confused, as all but the text 
literal are explicitly delimited. 


\ 
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6.0 PILOT Commands and Syntax 

I^ S imn^i,°\ S ? e - lf , ieS the syntax of each o£ the commands that 

?n -?K ln a ” PIL0T - Flrst the commands that are 
?iii’ Ute !» u either run mode or immediate mode are defined, 
ol lowed by those that are executed only in immediate mode. 


6.1 PILOT r un/ imrned i a t e mode commands 

cSnsSle nl whfl S p . d fn C - ibS 1- ^ thi f section raa y be executed from the 
c nsole while in immediate mode or may be entered to the proqram 

storage area to form a program. The same syntax checking~and 

semantic processing is applied in either mode, so no special 

ru es have to be remembered. Immediate mode command execution 

accesses the same data base as run mode command execution, so 

the user may interact with his program's data as an aid in 
debugging . 


6.1.1 TYPE Commands (T, 
information to the text 
is evaluated as a t 
5.2.3) and then output 
command processor assur 
right margin of the tex 
exceeds the defined scr 
terminated by an <EOL>, 
synonymous, except when 
'V, in which case the 


Y or N) -- These commands output 
screen. The data to the right of the 
ext expression (as described in section 
to the screen. Logic within the Type 
es that no word will be broken at the 
t screen, unless that word's length 
een width. Every physical line output is 
so that logical and physical lines are 
the last character to be output is a 
\' and the <EOL> are both suppressed. 


C C^Ser*'* 
fc D Ii&ujLuaZ-' 


tW ° f lter " ate names provided for the Type command: 'Y' 

^ latl0n f ° r ,TY ’ Snd ' N * is an abbreviation for 'TN': 
note that the command forms 'YY', 'YN', 'NN' and 'NY' are 

syntacticaliy proper under this implementation, but are either 

re undant (as m 'YY') or result in statements that will never 
execute (as m 'YN'). 

<type operand> ::= <texp> [\] 


Examples : 


T : $NAME IS #A YEARS OLD 

will produce JACK IS 10 YEARS OLD if $NAME=JACK & #A=10, 
or $NAME IS 0 YEARS OLD if $NAME is undefined & #A=0. 

T: 

will produce an empty line (<EOL> only) . 


c<animand The Accept command allows the user 

to enter data from the text screen to an internal storage area 

known as the accept buffer. The Accept command allows one or 
two optional operands to the right of the if a strina 

variable name is the first operand, then the accepted data is 
stored in that variable as well as in the accept buffer. If the 
first operand is a numeric variable, then if the accepted data 
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contains a numeric constant anywhere in the text, the value is 
stored in the variable or if the accepted data is totally non- 
numeric then the value will be zero (no error message will be 
generated). The input of an empty line (<EOL> only) will result 
in a numeric variable being set to zero, and a string variable 
being set to the null (empty) value; note that null strings are 
not the same as undefined strings. 



*- ”" ** " ■ ■■ ■■ 


than having PILOT go to the console to get accept data. 


If an '=' operator is present, then the text expression to the 
right of the '=' will be assigned to the accept buffer, rathepr ( 

■VlV'-ea 

> v c -vrv\ \>j(i v* \ e-i "to 

All accepted data goes through the following transformation aSh^V^^ 
it goes to the accept buffer (but not to the optional string 
variable) : 


A space is inserted at the beginning of the accepted data. 


A space is inserted at the end of the accepted data. 


All lower case alpha characters are converted to upper case. 
All multiple spaces are converted to a single space. 

The accept buffer is 254 characters in length and if the 

accepted data exceeds that length the (tail end of the data will 
be truncated. 


<accept operand> 


Ex iinples : 
h : 

A ; #A 
A : $NAME 
A : =$LEFT 
A : $WHAT=HI $NAME 


: := [<numeric variable> I <str ing variable>] 
[=<texp> ] 


Accepts 
Sets # A 
Assigns 
Assigns 
Compl ex 


data to the accept buffer only, 
to the numeric value entered, 
to $NAME the text literal entered, 
the value of $LEFT to accept buffer, 
assignment to buffer and variable. 


If the user program requires that numeric data be input when 
asked for, the code sequence shown below will suffice: 


*NUMIN A : #N [ ACCEPT A NUMBER. 

M:0, 1,2, 3, 4, 5, 6, 7, 8, 9 
TN: Please enter a number. 

JN : *NUMIN 


\ 



6.1.3 MATCH Command (M) -- The Match command scans the current 
content of the accept buffer, trying to find an exact match with 
one of the Match command fields. The operand is a text 
expression which will evaluate to one or more match fields 
separated by commas or, optionally, vertical bars. As always, 
blanks have significance in text expressions. If a match is 

found, the internal match flag is set true (= 1 to n, where n is 
the ordinal number of the match field producing the match); if 
no match is found, the match flag is set false (= 0). This flag 
is the one that is tested by the statement conditional operators 
'Y* and 'N', is used in evaluating the Jump match command, and 


- 18 - 




± _L 




Lj a 1 li 1\l\ A 


KuVibiUN b -- ^/-UCC-tiU) 


also generates the value for the special variable '%M'. 

<match operands> :: = [<vertical bar> ] [ <sk ip> ] Cmatch list> 

[<field sep>] 

<sk ip> : <right a r r ow> | <sk ip> <r ight arrow> 

<match list> ::= <match field>| 

<match listXfield sepXmatch field> 

<field sep> : := <comma> I <ver tical bar> 

Cmatch f ield> : : = (<ATASCII characters, not including the 

field separator or EOL character>] 

If the first character of the operand is a vertical bar ('|'), 
then that character will be the field separator for the match 
list, instead of a comma. If the first character of the operand 
is anything other than a vertical bar, then the field separator 
will be a comma. There is no situation in which both the 
vertical bar and comma may be field separators at the same time. 

Cursor right characters (ESC CTRL-*) appearing at the beginning 
of the operand (they may start after the optional vertical bar) 
will cause pattern matching to start at the n+lth character of 
the accept buffer, where n is the number of right arrows 
specified. A single right arrow is used to allow pattern 

matching to start after the omnipresent leading blank character 
in the accept buffer. 

Examples : 

Tries to match words (note blanks). 
Functionally identical to above. 

A less precise matching of character 
substrings within words. 

Uses a string variable containing 
the match fields. 

Matching for punctuation marks, 
including a comma. 

The scan algorithm used in the Match command scans the accept 
buffer to find a possible occurrence of the first specified 
match field, if none is found then the accept buffer is scanned 
to find an occurrence of the second specified match field, etc. 

unt il ^ match is found or there are no more match fields. 

Several special cases are shown below: 

M: Null operand is not allowed. 

M: ' Will match anything (null match). 

M :THIS , THAT ,, OTHER Will match anything (null match). 


M: YES , YEAH , SURE_ 
M: YES , YEAH , SURE , 
M: YE, SURE 

M : $VERBLIST 

M: I . I ; | , | : 


6.1.4 MATCH (Producing) STRINGS Command (MS) — The Match 
Strings command behaves exactly the same as the Match command, 
and also produces three named strings as a result of any 
successful match. $LEFT will have a value equal to everything 
to the left of the match, $MATCH will have a value equal to the 
match data, and $RIGHT will have a value equal to everything to 
the right of the match. Any of these strings may have null 
values, depending upon where the match occurred within the 
accept buffer data. If the attempted match is unsuccessful, the 
three strings will retain the values they had prior to the 
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command execution. 

When <right arrow> operands are specified, and a successful 
match is made, the value of $LEFT does not contain the Accept 
buffer characters skipped over by the <right arrow>s. 

<match operands> ::= <same as for the Match command) 

Example : 

A : =THIS IS A TEST. 

MS: IS , WAS , WILL BE , 

$LEFT = ' THIS' 

3MATCH = ' IS ’ 

$RIGHT = 'A TEST. ' 


MS:-> Match first imbedded blank. 


A : =WHAT WILL HAPPEN? 
MS:>>>_ 

$LEFT = 'AT' 

$MATCH = ' ' 

$RIGHT = 'WILL HAPPEN? ’ 


6.1.5 COMPUTE Command (C) -- The Compute command assigns the 
value of a numeric expression to a numeric variable or assigns 
the value of a text expression to a string variable. 

<compute operand> ::= Cnumeric var iable>=<nexp> I 

<string var iable>=<texp> 


Examples : 

C:#L=#L-1 Decrements variable #L. 

C:#C = 1 Assigns the value 1 to #C. 

C : #A=3 1 4 * #R* #R/ 10 0 #A = 3.14 * #R**2. 

C : # J = #J-(#A/2) Assigns new value to #J. 

C :$ADDRESS=#N $STREET GILROY Assigns to $ADDRESS the 

concatenation of the value of #N converted to 
ATASCII, followed by the value of the string 
$STREET followed by the text literal GILROY. 
C:$$TEMP = $RIGHT String indirection O.K. 


6.1.6 REMARK Command (R) -- The Remark command allows for the 
insertion of remarks into the body of a PILOT program. The 
condition field result has no effect upon the action of this 
command, except for slight variations in the time to execute. 
That is to say, 'R', ' RY ' and 'RN' are all equivalent. 

Cremark operand> : : = <anything> 

Examples : 
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R:* 

R:* 

R:* 

R:* 

R:* 


PILOT PROGRAM "TEACHER" 

21 -AUG- 79 


★ 

★ 

★ 

* 


^ ’ ******************************** 


6.1.7 JUMP Command ( J ) -- a run 

runninq oroaram »-« l •? de Jum P command allows the 

execution a? the sta^en“witT the speemfd 0 ^! 00 "^™ 1 " 9 

p“gram t 2xelutionTt 1 'tiie speculei” £V nt,r Cmm ° ae "" d Sta “ 

command execution, no iniUM zatfo^of'' COn “ ar y to Ru " 

accept buffer or the screen will !°? of variables. Use stack, 

statements have the specified 1 hlf 2 ^ 306 * If tW ° ° r more 
line number will^ ^ ^ ^ 

< jump operand> : := <label> 


Examples : 


J : *L00P1 
J : *BEGINNING 


the* running ^progr am'to ^ jump'to^one^of^ °" "-f 6 ? b °“ a " d ^ows 

Jump to one of several labeled 


successful „,>h Zh Zu , ^eio; ir tne match was 

be used or ”t he n'umo Tf^h field ' the nth ° per3nd label will 

,.f “f ° r ? r tne Jump. if the prior Match was unsuccessful or 
l£ there is no nth operand label, no jump will be executed 

descllbed ?o° e tb eXe ? Uti ° n ° f 8 JUmp °" =°™and 
-scribed for the Jump command. 


is as 


<jump match operand> : := <label> [<sep>< 
Examples : 


jump match operand>] 


JM:*L1 *L2 *L3 

JM : *HERE , * THERE , * EVERYWHERE 


B^sir rnlin j U) ~ The Use comm ^ correspond: 

BASIC GOSUB command. it allows the program to alte: 

flow to invoke a subroutine, and when the subroutine 

control is returned to the statement following the J 

Up to eight (8) Uses may be nested before the^yster 

h ? rror messa 9s- Immediate mode execution of 

command is as described for the Jump command, with 

exception that the Use stack is cleared. 


to the 
the linear 
is done, 
e command, 
responds 
Use 

e 


<use operand> : := <label> 
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Example : 

U : *GETDATA 
U:*SQRT 


6.1.10 END Command (E) -- The End command tells the interpreter 
to return to the statement following the most recently executed 
Use command, or to stop the execution of the program if there is 
no Use return stacked. This command, as all others, may be 
conditional, and there may be any number of them in a program 
and/or subroutine. Immediate mode execution of an End command 
is as described for the Jump command, with the exception that 
execution starts at the statement at the top of the Use stack. 

If the Use stack is empty, PILOT immediately reverts to 
immediate mode. 

<end operand> : := <null> 

Examples : 



E : 


6.1.11 NEW VARIABLES Command (VNEW) -- The New variables command 
allows the selective clearing of the numeric variables and/or 
the string variables. If the operand is null then both variable 
types are cleared, and if the operand is '$’ or '#', then the 
string or numeric variables (respectively) are cleared. Note 
that when the string variables are cleared, any currently active 
READs or WRITES are closed. 

<vnew operand> ::= [$l#] 

Examples : 

VNEW : $ 

VNEW:# 

VNEW: 


Clears the string variables. 

Clears the numeric variables. 

Clears both the numeric & string vars. 


6.1.12 GRAPHICS Command (GR) -- The Graphics command allows the 
user to move a cursor around the graphics screen and to draw 
line segments and plot points of various colors. There is one 
PILOT command provided to handle all of the graphics 
capabilities, as the operand field actually contains graphic sub- 
commands that do the graphic manipulations. The graphics sub- 
commands constitute a language within the PILOT language and 
differ syntactically from core PILOT; for example: multiple sub- 
commands may appear in one line, there is an iteration 
construct, etc. 

<graphic operand> : := <graphic sub-command> [ ; <graphic operand>]| 

<iterate count> (<graphic operand>)| 
<iterate countXgraphic sub-command) 
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<iterate count> : := <numeric constant> | <nurner ic variable> 

For example: GR: GOTO 0,0;TURNTO 0;4(DRAW 10;TURN 90) draws a 
square with the lower left corner at the screen center. 

Note that the iterate count must be specified as a positive 
integer that will be decremented until zero is reached; thus 
iterate counts may range from 0 to 65535. 

PILOT supports two drawing systems, a cartesian system of X,Y 
points and a polar system of R, THETA vectors (turtle graphics). 
Both systems are available at all times, and there is no problem 
in mixing sub-commands that deal with both systems. The 
coordinate directions and reference points are listed below: 


X-0, Y-0 is at the center of the graphics screen. 

Increasing X goes to the right. 

Increasing Y goes upward. 

THETA=0 is straight up. 

Increasing THETA is clockwise. 

Increasing R is in the direction of THETA. 

The inside left edge of the graphics screen is X = -79. 

The inside right edge of the graphics screen is X = 79. 

The inside top edge of the graphics screen is Y = 47. 

The inside bottom edge of the graphics screen (top of text window) 
is Y = -31 . 

The inside bottom edge of the graphics screen (bottom of text 
window) i-s Y = -47. Although the graphics data in the region 
-47<Y<-3i is not visible to the user, it may be sensed by the 
program (using the %Z special variable). ... 


If, when a Graphics command is executed, the screen is not in 
the graphics mode, the screen is put into the graphics mode and 
cleared, the cursor is put at home position, THETA is set to 
zero and the pen color is set to YELLOW. This same 
initialization of the graphics parameters will occur also upon 
the following conditions: 


Power-up. 

Run command. 


DOS. 


■2r~ 






For all commands that draw lines or set the graphics cursor, if 
the cursor or line leaves the bounds of the visible graphics 
screen, the position will be maintained within a +/- 32767 
sddress space; whenever the cursor and/or line re-enters the 
visible graphics screen, drawing will resume. The graphics sub- 
commands will be described in the paragraphs that follow: 


PEN -- Pen color select. 

Sets the drawing pen to one of the five options provided. 

<sub-command> : := PEN <color> 

Ccolor > ::= RED | YELLOW | BLUE | ERASE | UP 
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Example: PEN RED 


QUIT -- Quit graphics mode. 

Returns the screen to the text screen. 

< sub— commands • • — QUIT 
Example: QUIT 


n x Y without drawing line. 

GOTO -- Move cursor to x,i 

. . . * v v coordinate and plots a 

MOV- ^ t -r?oo^in^e S ?n C ^r^;ent pen colot. » the pen 
point at tnar ^ , nnl hp clotted, 

is UP, then no point wil P 


<sub-command> 

<x-coordinate> 

<y— coord inate> 


GOTO < x-coor d ina te> < s ep> 
<nexp> 

<nexp> 


-coord inate> 


Examples: GOTO tJ+3,20 

GOTO 40,-10 


, x. i_ u ^ » * ■? a required as 
Note that the , 1S M ,, n 

■40 -10' would be ? r i°id?nf a value o£ 
single expression yieiai g 

30. 


ho x Y while drawing a line. 
nRAWTO -- Move cursor to x, 

... - x Y coordinate while drawing a 

Moves the cutset to the speci *«$*;*,« : pen ls 0P , then no Une 
line of the cut tent pen «1«; unchang ed. 
will be drawn. iHEift 


<sub-command> 

<x-coordinate> 

<y-coordinate> 


DRAWTO <x-coordinate><sep><y coordin 

= <nexp> 

= <nexp> 


Example: DRAWTO #1 #J/2 

to X Y while drawing a line and^£illi n 9» 
FILLTO -- Move cursor to X,Y wnix 

... , x y coordinate while drawing 

^n e e S of he the U c S utten°t pen colot; in addition blank -fons^to^ 

l[ s r i^UP. 9 then 1 no 6 line ot Oil .iU be 

pen color also. in- 
drawn. 


<sub— command)* : 

<x-coordinate> 

<Y_ coord inate> 


= FILLTO <x-coordinateXsepXy-coordin 

: = <nexp> 

: = <nexp> 


Example: FILLTO 40,-10 




X UV X 
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1URNT0 Set polar angle to value in degrees. 

Sets the polar angle THETA to the value of the expression, 
modulo 360. 

<sub-command> : := TURNTO <angle> 

<angle> : := <nexp> 

Example: TURNTO 90 


GO -- Move the cursor forward by n units. 

Moves the cursor forward (along the direction specified by 
THETA) the number of units specified and then plots a point in 
the current pen color at the end point. If the pen is UP, then 
no point will be plotted. If the number of units specified is 
negative, the cursor will move backward instead of forward alonq 
THETA. 

<sub-command> ::= GO <units> 

<units> ::= <nexp> 

Example: GO 20 


DRAW - Moves the cursor forward (along the direction specified 
by IHETA) the number of units specified, while drawing a line of 
the current pen color. If the pen is UP, 'tan no line will be 
drawn. If the number of units specified it, negative, the cursor 
will move backward instead of forward along THETA. 

<sub-command> : : = DRAW <units> 

<units> ::= <nexp> 

Example: DRAW #L 


FILL Moves the cursor forward (along the direction specified 
by THETA) the number of units specified, while drawing a line of 
the current pen color; in addition, blank regions to the 
right of the line being drawn are filled with the current pen 
color also. If the PEN is UP, then no line of fill will be 
drawn. If the number of units specified is negative, the cursor 
will move backward instead of forward along THETA. sc^o^. 


< sub-command> : := FILL <units> 
<units> ::= <nexp> 


Example: FILL 30 


TURN — Increments the polar angle by the number of degrees 
specified: THETA = (THETA + increment) MOD 360. 

<sub-command> ::= TURN <angle> 
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<angle> ::= <nexp> 
Example: TURN 30 


cs and text screens, 
screen and the text screen window. 

<sub-command> : := CLEAR 
Example: CLEAR 


CLEAR — Clear the graphi 
Clears both the graphics 


There are four special "read only" variables (as mentioned in 
section 5.1.5) associated with the Graphics command; the 
attributes of these variables are discussed in the paraqraphs 
that follow: 

%X returns the current value of the x-coordinate of the 
graphics cursor, rounded to an integer value. 


%Y returns the current value o 
graphics cursor, rounded to an 

%Z returns the current numeric 
at the current graphics cursor 
equivalents are shown below: 

ERASE (background) = 0 
RED = 1 
YELLOW = 1 
BLUE = 3 


the y-coordinate of the 
integer value. 

equivalent of the screen color 
location. The numeric 

Ov,ill v«.4virwv. 


If the cursor 
if the screen 
returned . 


is outside the bounds of the graphics screen, or 
is not in graphics mode, a value of 0 is 


%A returns the current value of the graphics THETA angle. 


— -£-^4 poiuff - Si4~ua4"L<r-i D^AU) m . ' L/t/HxJ _ /vu — - 

— 

Grfc*p\uc 5 Vaao 4<2_ oue^rie. . 
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Command (SO) -- The Sound command enables or 
disables the sound generating facilities within PILOT 

°? e - a K? S ; ? f KMch thete ”«y »= up to four, specify th 

5T w£S?If n?eae? ‘ :?S2njs? -*-» P ?"n- c «f ,: 2-S".fiS5lS-SS 1 f h r5i;ue 


e numeric 
are to be 


1 = C below middle C 

2 = C# below middle C 

3 = D below middle C 

• 

13= middle C 
25 = C above middle C 
31 = F# above C above middle C 
When the value exceeds 31, the value modulo 32 is used. 


Sin^e the hardware sound generation 
voices in parallel, up to four voice 
hardware sound registers are updated 
PILOT statement. At that time the c 
variables and pointers are obtained 
the tones changing as the variables 
change; the numeric constants select 
expected. Note that due to the natu 
pointers to addresses above 32767 wi 


circuitry will support four 
s may be specified. The 

^fter the excution of every 
urrent value of the 

and converted to tones, with 
(and pointed to data) 
constant tones, as would be 
re of the implements tion , 

11 produce static tones. 


<sound operands> 


<sound variable> 


[ <sound variable> [<sep><sound 
[<sep><sound variable> 
[<sep><sound var i able> ] ] ) ] 
<numeric var iable> | <pointer> | 
<numeric constant> 


var iable> 


disabled^ 136165 ^ present ' the sound generation will be 
Examples : 


SO : #A 

SO : #D #G #K 
SO: 

SO:@4096,@B764,@#P 
SO: 1,5,8,13 


Generate sounds using variable #A 
Generate sounds using 3 variables 
Disable sounds. 

Generate sounds using pointers. 
Generete constant tones. 


f * P ^ USE £ omma " d ( pA ) The Pause command delays the 

indicated number of 1/60S of a second before executing the next 

command This command is used to synchronize music and 

graphical presentations to some fixed time base as th- delav is 

thanTi 1Shed f? y exm " lnin 9 the hardware generated timer rather 
than by a software delay loop. 

<pause operand> ::= <nexp> 


Examples : 
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PA : 60 

Delays one second. 



PA: 0 

No delay. 



PA : 1 

Delays to the next 

clock 

tick . 

PA: 2 

Delays to the next 

clock 

tick + 1 . 

PA : #D 

Delay specified by 

variable #D. 


6.1.15 CASSETTE TAPE CONTROL Command (TAPE) -- The Tape command 
turns the Cassette peripheral motor on or off as indicated by 
the supplied operand, which must be either ’ON' or 'OFF'. 


Ctape operand> ::= ON|OFF 
Examples : 

Turns the Cassette peripheral on. 
Turns the Cassette peripheral off. 


TAPE :ON 
TAPE : OFF 


6.1.16 CASSETTE TAPE SYNC Command (TSYNC) -- The Tape Sync 
command allows a PILOT program to synchronize itself to a 
specially prepared cassette tape which has an audio track plus 
synchronization information on the digital track, such as the 
'Invitation to Programming' tape. The Tsync command checks the 
cassette motor drive status and if the motor is not on, then the 
command is done. However, if the motor drive is on (probably 
as a result of a prior 'TAPErON') then the Tsync command will 
read the cassette digital track and wait for a MARK (1) to SPACE 
(0) transition. 

<tsync operand> ::= <null> 

Example : 

TSYNC : 


6.1.17 I/O Commands -- The I/O commands (READ, WRITE & CLOSE) 
provide the ability to read data from and write data to any of 
the peripheral devices. The syntax and behavior of each of these 
commands will be described in the paragraphs to follow, but 
first a discussion of their common points would be in order. 

All three commands require a device specification as the first 
command parameter; this specification may be in the form of a 
text literal (e.g. P or C or DrELIZA) or may be a string name 
(e.g. 5DEVICE or $F1 or $PRINTER) where the value of the string 
is a valid device/filename. There is no explicit OPEN type of 
command provided; the first use of the name in an READ or WRITE 
command will attempt to OPEN the device (subject to available 
internal resources and the legality of the device/filename). 

The number of devices which may be accessed in parallel is 4 and 
there are no restrictions as to the mix of input and output 

types . 

<device spec> : := <text 1 i teral> I <str ing variable> 

The evaluation of <device spec> must produce a valid Atari 
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400/800 <device/f i lename> . 


READ Command (READ) -- The Read command allows data to be read 
from one of the attached peripheral devices to the accept 
buffer, with the data transformation rules being applied as 
described for the Accept command (section 6.]. 2). Optionally, 

data may be read to either a numeric variable or a string 
variable as well. 

Cread operand> <device spec> f <sep>< i nput variable>] 

<input var iable> : := <numeric var iable> | <string variable> 

Examples : 

READ: C , $DATA 
READ: $FILE1 , #N 

If a device end-of-file status is read, the Read command will 
return null data. 


WRITE Command (WRITE) -- The Write command allows data to be 
written to one of the attached per ipheral devices. The data to 
be written will be the evaluation of a text expression. 

<write operand> ::= <device specXs 

Examples : 

WRITE :C , JOE IS #A YEARS OLD. 

WRITE : $DEVICE #N 
WRITE : P, $J 32 #C A BCD. 


CLOSE Command (CLOSE) -- The Close command is the equivalent of 
CLOSE in roost languages. Internally, the IOCB associated with 
the named file is freed for use by another named file, and for 

some peripherals (such as the disk) special termination actions 
are initiated. 

Cclose operand> : := <device spec> 

Examples : 

CLOSE :C 
CLOSE :D: STAR 
CLOSE :$DEVICE4 



Advanced I/O discussion — The next few paragraphs discuss 
special aspects of the Atari PILOT I/O subsystem. 

I/O Errors -- Any I/O error will normally cause termination of a 
running program and will also cause the file in error to be 
closed. An error message will be generated which will inform 
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the user of the type of er 

However, all of the^a-oove 
mode) by sett ina^r6cat ion 
value. The status of the 
then be checked by examini 
value of 0 ^indicates that 
128-255 indicate I/O error 
errors, an EOL character i 
simply ignored. The inhib 
and all immediate mode I/O 
message . 


s shown in Appendix C. 


^ ‘vec^a'ieCy 
a*£W 


or X 

activities may be inhibited (in run 
$0500 (1 280 decimal) to any non-zero 
prior READ, WRITE or CLOSE commland may 
ng location $00E4 (228 decimal)!; a 
the operation was normal, and values 
s as shown in Appendix C. On READ 
s returned; WRITE and CLOSE errors are 
it flag is ignored in immediate mode 
errors will produce an error 


The inhibit flag is 
conditions : 


set to zero by PILOT upon the following 


Power-up . 

RESET. 

Any reported error. 
Return to immediate mode 
Immediate mode BREAK. 


from run mode 


errn? f 5n^ e ~ End-of - f i l e status is not considered to 
error, and will result in null data being read. Since 

shoniM ls .[ lot e asily accessible via a PILOT construct, 

bv^ nr tn S<= T e * tra data at end of any file to 

of the fUt S the E ° F t0 the Pr°9 ra * doing the 

tn_ file. See the program example below: 


@> 822 . 8-/ 2 

be an 
the I/O 
the user 
be read 
reading 


1 00 C : $F I LE=C 

110 C:#L=1 

120 *L00P1 

130 WRITE:$FILE,#L 

140 C :#L=#L+1 

150 J (#L< = 3 00) : *L00P1 

160 WRITE : $F ILE ,** * EOF 

170 CLOSE : $FILE 

200 C : $F I LE=C 
210 *LOOP2 
220 READ: $FILE , #N 
230 M:*** EOF *** 

240 TN : NUMBER = #N . 

250 JN : * LOOP 2 
260 C LOSE : $F I LE 
270 E: 


Set filename to Cassette. 
Initialize loop count. 

Output numeric data from 1 



• • 


* * * 


to 100. 

Write user EOF data. 
Close the file. 

Set filename to Cassette 

Read numeric data. 

Check for EOF. 

Print data if not EOF. 
Loop back if not EOF. 
Close the file. 

End of program. 


Bi-directional I/O — Atari PILOT I/O is inherently 

deJeJm!ned°£? ihe in?ti^ n ° °wn command a " d «>e direction is 
mined by the initiating I/O command (READ or WRITE) 

eSiw/; E ?° m ;Ld e tir S are such as the screen 

_ j ' " nd user may want to perform concurrent reads 

and writes when using this class of device. This is done bj 

specifying ^ synonyms for the device/filename, e.g. •£■ 

El, a nd El:* are all valid ways of specifyinq 
ha 1 tor. Note that each synonym is treated 
by the PILOT I/O subsystem. 


fy 

as 


1 p . i 

/ A-» • f 

ng the Screen 
a separate device 
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fn5= of °? en ? lle s -- PILOT maintains a list of currently open 
lies; this list is comprised of string variables, where the 
string name is the device specification appended to and th® 

?n^o ng V - 6 3 sin< 3 le character which indicates the internal 

IOCB assignment. These strings are of no interest to the PILOT 
user except that they appear in the string variable list 
produced by the Dump command, and clearing the string variables 
using the Vnew command has the effect of closing all files. An 
example of these special strings is given below: 


$@C=’ @ ' 

$ 0D : ELI ZA= ' P ' 


Cassette is assigned to IOCB 4. 
Disk file 'ELIZA' on IOCB 5. 


Note that '0' is IOCB 4, 
IOCB 7. 


'P' is IOCB 5, '❖' is IOCB 6 & 'p* is 


raphics conflict error -- There is a check that prevents I/O 
operations that would destroy the graphics screen. If the user 
esires to READ from or WRITE to the Screen Editor ('E') or the 
Display handler ('S') when the screen is in graphics mode, th<= 
first READ/WRITE (with its implied OPEN and screen clear) must 

^A^/,,ox f ° re establishin g the graphics screen, then subsequent 
READ/WRITE operations will be allowed. 


IOCB AUX1 & AUX2 control -- Normally PILOT establishes 

values for AUX1 and AUX2 of each IOCB at OPEN time, as 
below: 


the 

shown 


Command AUX1 AUX2 

READ 4 0 

WRITE 8 0 

LOAD 4 0 

SAVE 8 0 


he advanced user may force other values for these variables by 
writing a byte into location 1373 (decimal) for AUX1 and into 
location 1374 (decimal) for AUX2. PILOT will then "inclusive- 
or the user supplied byte with the constant shown in the table 

USer™n!’rn??^ h Vi: SUlt ^ I0CB 3t ° PEN time * The two 
ser controllable bytes are reset to zero as shown below: 


Power-up . 

RESET. 

After every usage (OPEN) . 

\ 


6. 1.1 8 POSITION CURSOR Command (POS) — The Position command 

allows the user to control the position of the cursor while in 

e text screen, just as the GOTO sub-command controls the 

cursor for the graphics screen. The two Position operands 

specify a column number ranging from 0 to 39 and a row number 

ranging from 0 to 23; the upper left corner of the text screen 
being 0 , 0 . 


When the screen is in graphics mode, the specified column 
applies to the text window and the row number is ignored. 


number 
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<position operand> ::= <column><sep><row> 
<column> ::= <nexp> 

< r ow> : : = <nexp> 

Ex amples : 

POS : 4 0 , 2 
POS:#C,#R 


6.]. 19 TRACE Command (TRACE) — The Trace command allows the 
user to monitor the execution of the program while in run mode. 
When turned on, the trace will print to the screen each 
statement scanned, prior to its execution. Conditional 
statements will be printed whether or not the condition is 
true. Every trace line is preceded by the four characters 
in order to make the trace lines stand out from Type, Accept, 
Read and Write data on the screen. 

<trace operand> ::= ON|OFF 

Examples : 

TRACE :0N 
TRACE :OFF 

A typical trace output to the text screen is shown below: 

--> 10 T: HELLO, WHAT IS YOUR NAME? 

HELLO, WHAT IS YOUR NAME? 

--> 20 A : $NAME 
JACK 

--> 30 T : GOODBYE $N AME . 

GOODBYE JACK. 

--> 40 E: 

READY 


6.1.20 DUMP Command (DUMP) — The Dump command is used to list 
to the text screen the contents of the string variable list. 
Shown below is an example of Dump command output: 

$NAME= 'JOE ' 

$RESPONSE= 'NO ' 

5STRING1 = ' I LIKE TO PLAY BALL' \ 

$ STRING 2= 'GREEN ' 

$NULL= ' ' 


6.1.21 LOAD Command (LOAD) — The Load command allows the user 
to read a previously saved PILOT program to the stored program 

area (see section 6.2.3 for information on how to save a 
program). The required operand is a text literal. that specifies 


the device/filename. 

<load operand> ::= <device/f i lename> 


* 
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Examples : 


LOADtC Loads a program from the cassette. 

LOAD: D: SQUARE Loads the file 'SQUARE' from Disk #1. 

Lo *VD : $ FXLEKiA M£ 

If the Load command is executed in immediate mode, the stored 
program area is not cleared prior to the loading; if a program 
is in the storage area prior to a load, the two programs will 
be "merged". 

If the Load command is executed in run mode, the stored program 
area is cleared prior to the loading of the specified program 
(and the Use stack is cleared). If the load process encounters 
no errors (file I/O or statement syntax) the newly loaded 
program will be executed without any inititialization of the 
program environment, except that the Use stack is cleared. 

Load reports any syntax errors encountered during the load 
process and continues loading until either an I/O error or end- 
of-file is encountered. Any statement with a syntax error is 
not stored in the deferred program storage area. 


6 

u 

■ 

1 

6 

r 

r 

s 

• 


.1.22 CALL Command (CALL) -- The Call 
ser to execute 6502 machine language c 
nterpreter execute a J3R to a user spe 
502 code starting at that address need 
eturn to the PILOT environment. The 6 
egisters are available to the called r 
aved and restored. The PILOT interpre 
nterrupts and clear decimal mode immed 


command allows the PILOT 
ode by having the PILOT 
cified address. The 
only execute an RTS to 
502 A, X, Y and P 
outine and need not be 
ter will enable IRQ 
iately upon return. 


<call operand> 


<nexp> 


Examples : 


CALL: 4096 
CALL : #A 
CALL: @4 096 


JSR to location 4096 decimal. 

JSR to location specified by value of #A. 
JSR indirectly through location 4096. 


\ 
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6.2 PILOT immediate mode only commands 

This section describes those commands that may only be executed 
while the system is in immediate mode; that is, they are 
restricted to use by the operator. 

For the immediate mode only commands, the condition field 
delimiter may be omitted if desired. Thus, for example, 

either 'RUN' or 'RON:' will be accepted as a legal form of the 
Run command. In addition, the following run/immediate mode 
commands have this same feature: TRACE, VNEW, DUMP and LOAD. 


6.2.1 LIST Command (LIST) -- The List command is used to list to 
the text screen the current contents of the program storage 
3 fga . Screen control characters will^be displayed rather than 
being interpreted. The List command will display either the 
entire program area or a selected portion thereof (if beginning 
and ending line numbers are provided). 

<operands> : := [<line # > [<sep><l ine #>]] 

Cline 1> : := Cnumeric constant> 

Examples : 

Lists all of the program area. 
Lists lines 100 through 200. 
Lists line 500. 


6.2.2 RUN Command (RUN) — The Run command changes the operating 
mode from immediate to run; execution starts at the lowest 
numbered line in the program storage area. Before the stored 
program is started, the Use return address stack is cleared, the 
accept buffer is cleared, all variables are cleared, the screen 
is cleared and the Match result flag is set to false. 

Crun operand> : := <null> 

Example : 

RUN 


LIST 

LIST 100 200 
LIST 500 



6.2.3 SAVE Command (SAVE) — The Save command allows the user to 
save all, or portions of, the current PILOT deferred program to 
a specified external device. Tie required first operand is a 
text literal that specifies the device/filename; the optional 
operands specify line numbers which have the same function as 
for the List command (see Section 6.2.1). 

<save operands> : := Cdev ice/f i lename> [ <1 ine #> [CsepXline #>)] 
Cline #> :: = Cnumeric constant> 


Examples : 
SAVE P 


Prints the program to the Printer. 
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SAVE C Saves the program to the Cassette. 

SAVE P, 200, 300 Prints program lines 200 through 300. 


6.2.4 DOS Command (DOS) -- The Dos command allows the user to 
leave the PILOT environment and enter the environment of the 
Disk Operating System Utility. If the DOS is not resident, 
control will be passed to the Blackboard program. PILOT may be 
resumed by use of the DOS 'B' command or by pressing the RESET 
key. The return to PILOT finds PILOT in the same state as after 
the RESET key has been pressed, even if the 'B' command is used 
to return. 

<dos operand> <null> 

Example : 

DOS 


6.2.5 NEW Command (NEW) -- The New command allows the user to 
delete the program stored for deferred execution, to remove 
all string variables from storage and to zero the numeric 
variables; the Use stack is also cleared in the process. The 
memory that was used to store the program and strings is then 
available for any use. 

<new operand> <null> 

Example : 

NEW 


6.2.6 AUTO-NUMBER INPUT Command (AUTO) — The Auto-number Input 
command allows the user to enter the auto-number input mode. In 
that mode PILOT statements are entered from the screen and those 
that are error free are appended to an internally generated line 
number and stored to the deferred program area. The line 
numbers start with the number specified by the optional first 
operand of the command and are thereafter incremented by the 
value of the optional second operand. The operands, if not 
specified, default to the value 10. 

I 

The text screen changes from white characters on a blue 
background to black characters on a dark gold background when 
auto-number input mode is active, and reverts to the normal 
colors when the mode is inactive. The entry of an empty line, 
or the generation of an invalid line number, terminates the 
mode and causes a return to immediate mode. 

<auto operands> ::= [<line # > [ <sep> < i ncrement> ] ) 

<line #> : := Cnumeric constant> 

< increment> <numeric constant> 

Examples ; 
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AUTO 


Enter 

auto-number 

AUTO 

10,10 

Same 

as above. 

AUTO 

100 

Start 

with line 1 

AUTO 

100,20 

Start 

with line 1 
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input mode. 

0, increment 
0, increment 
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by 10. 
by 20. 


6.2.7 RENUMBER Command (REN) -- The Renumber command allows the 
user to renumber the PILOT program statements in the program 
storage area. The new line numbers start with the value of the 
optional first operand and are thereafter incremented by the 
value of the optional second operand. The operands, if not 
specified, default to a value of 10. 


If during the course of the renumber process an invalid line 
number is generated (outside of range 0-9999), an error message 
is generated and the renumber process stops. The stored program 
is never reorganized by the Renumber command, so this condition 
can be easily corrected by renumbering again with different 
operand values. Note that if a partially renumbered program is 
SAVEd and then LOADed , the program will be reorganized at load 
time and a simple recovery will be impossible. 


Crenumber operands> : := [Cline # > [<sep> < i ncrement> ] ] 
Cline #> ::= Cnumeric constant> 

Cincrement> ::= Cnumeric constant> 

Examples : 


REN 


Renumbers 

the 

program. 



REN 

10,10 

Same as above 

# 



REN 

100 

Renumbers 

to : 

100, lit. 

120, 

3 30 , . . . 

REN 

200,100 

Renumbers 

to : 

200, 300. 

400, 

50 0, . . • 
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7.0 PILOT Message Responses 

Atari PILOT produces two types of messages, informative (non- 
error) messages and error messages. The display format for both 
types is similar. Atari PILOT responds to errors by displaying 
the statement in error, color inverting the character at (or 
just beyond) the source of the error, and generating a message 
explaining the error. There are two classes of errors: syntax 
errors, which are detected by scanning the PILOT statement when 
it is entered, and run-time errors, which are only detected as 
the statement is executed. Informative messages do not invert a 
character in the statement, because there is no error to point 
out. The rest of this section itemizes the Atari PILOT messages 
and elaborates on them somewhat. 


7.1 Syntax Errors 

WHAT’S THAT -- Indicates one of the error conditions specified 
below . 

The condition field is improperly specified or the is 

missing from the statement. 

After a specific command has been completely scanned, there are 
additional characters present in the statement. 

The statement command name (or Graphics sub-command field) does 
not specify an Atari PILOT command. 

The indicated character or word has no meaning to Atari PILOT 
within the context of the statement being examined: 

not followed by alphanumeric character (string var?). 

’#’ not followed by alphabetic character (numeric var?). 

’*’ not followed by alphanumeric character (label?). 

’ not followed by numeric data (pointer?). 

’%’ not followed by recognized character (special var?). 

An unrecognized special character outside of a text literal. 

The command operand flagged has one of the following problems: 

Out of range value. 

Incorrect data type. 

Missing operand where one is required. 

The numeric expression has been incorrectly specified and has 
one of the following errors: 

Too many levels of nested parentheses. 

Unmatched left paren. 

Unmatched right paren. 

Non-numeric operand. 

Missing or incorrect numeric operator. 

The Graphics sub-command operands have been scanned and one of 
the following conditions has occurred: 

Missing ’ ; ’ . 

Unmatched left paren. 
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Too many or too few oporands for a sub-command. 

% • 

LINE #? — The statement line number specified is negative or is 
greater than 9999. The error may occur during any of the 

following conditions: 

Immediate mode entry of a statement for deferred execution. 
Auto-number input mode entry of a statment. 

Renumbering a program. 

IMMEDIATE ONLY -- The command specified is allowed only in 
immediate mode and cannot be entered for deferred execution. 


7.2 Run-time Errors 


WHAT'S THAT? — Indicates an error in a command operand that is 
syntactically correct but has a semantic error, such as an_ out 
of range numeric variable, assignment of data to an invalid 
string indirection, etc. 

I/O ERROR xxx -- In the course of performing an I/O operation 
the I/O subsystem detected an error and returned the s a a 
indicated. See Appendix C for a list of I/O error codes. 

NO ROOM -- Indicates that the r quested operation could not be 
performed because there was not enough free memory. The creation 
of string variables, entry of deferred execution statements, and 
I/O initiation may all generate this message. 

WHERE? — Indicates that the target label for a Use or Jump 
command does not exist in the program storage area. 


U: TOO DEEP -- The program has exceeded 8 levels of nested Use 
commands . 

TOO MANY I/OS -- Indicates that there was an attempt to perform 
more than 4 concurrent READ/WRITE operations. 


DIVIDE BY G -- A Compute command has just attempted to perform 
a division by zero. 


OOPS -- An I/O operation involving the 'E' 
been aborted because it would destroy the 
greatly confuse PILOT. See section 6.1.17 
this error. 


or 'S' device has 
graphics screen and 
for a way to avoid 




7.3 Informative (non-error) Messages 

READY — Indicates one of the following conditions. 

An End command was executed with no corresponding Use return 
address in the Use stack (normal program termination). 
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The last line in the program storage area was executed and it 
was not an End or a Jump command, therefore there was no next 

program statement to execute. 

The operator has pressed the BREAK key; when this occurs while 
a PILOT program is running, the message is surrounded by *** 
The statement printed when a running program is stopped is the 

last to be executed or partially executed. 

One of the immediate mode only commands has just finished 
execution (or VNEW or LOAD while in immediate mode) . 

The operator pressed the RESET key. 


A PILOT program has just generated a run-time error; the error 
message precedes the READY message. 


(ATARI PILOT EXTERNAL SPECIFICATION, 
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Appendix A -- PILOT DATA SYNTAX SUMMARY 


This appendix lists the Atari 
giving an abbreviated version 


PILOT data types and operators, 
of the expected syntax for each. 


Sub-group 

Statement 

Numer ic 
data 


Text data 


Name 

Line # 

Label 

Comment 

Var iable 
Constant 
Random num 
Pointer 
Controller 
joystick 
paddle 
trigger 
1 ightpen 
Special 
free mem 
match 
g raphics 
Expression 
nexp 
unary - 
eval 


Syntax 


Section 


<0-9999> 

*<alphanumerics> 
(<text 1 i teral><EOL> 


# <alpha> 

[-] <digits> 

•p 

@ [B] <constant I variable I pointer> 
% <alpha> ( cnumber > ] 

%J<0-3> 

%P<0-7> 

%T< 0-11 > 

%H , %V, %L 
%<alpha> 

%F 

%M 

%X, %Y , %Z, %A 


5.1.2 
5.1.1 

5.1.3 

5.1.6 

5.1.4 
App F 
App F 
App F 
App F 

5.3.5 

6.3.3 

6.3.32 

5.3.7 


Cnumer i c entity> [<operator><nexp> ] 
-<nexp> 

(<nexp> ) 


Variable $ <alphanumer ics> 

Literal <any ATASCII character) 

Expression 

Indirection $<text variable> 


5.2.2 

5 . 2.1 

5.2.3 

5.2.4 


Operator 


Ar ithmetic 
add 

subtract 
multiply 
d iv ide 
modulus 
Log ical 
equal to 
not equal 
gtr than 
gtr/eq 
less than 
less/eq 


<numer i c> <ope ratorX numer i c> 
+ 

* 

/ 

\ . N 

< numer i c> <ope r a tor > (numer l c> 


<> 

> 

> = 
< 

< = 


5.1.7 


5.1.7 
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Appendix B -- PILOT COMMAND SUMMARY 


This appendix lists the Atari PILOT commands, giving an 
abbreviated form of the operand syntax. The complete command 
descriptions are to be found in Section 6. The type indicates 
whether the command is executed in immediate mode only (I) or 
both run and immediate modes (R/I). The core PILOT commands are 
listed first, followed by the Atari extensions; note that only 
the core PILOT commands have one character names. 


Command 

Function 

Operand syntax 

Note 

Type 

Section 

T 

Type 

<text expression> 

1 

R/I 

6.1.1 

Y 

Type if match 

<text expression> 

1 

R/I 

6.3.1 

N 

Type if no match 

<text expression> 

1 

R/I 

6.3.1 

A 

Accept 

f <var> ] [ = <texp> ] 


R/I 

6.1.2 

M 

Match 

Cmatch list> 

1 

R/I 

6.1.3 

C 

Compute 

<nvar>=<nexp> 
<svar>= (texp> 


R/I 

6.1.5 

R 

Remark 

<comment> 


R/I 

6.1.6 

J 

Jump 

<label> 


R/I 

6.1.7 

u 

Use 

<label> 


R/I 

6.1.9 

E 

End 

<nul 1> 


R/I 

6.1.10 

JM 

Jump on match 

<label list> 


R/I 

6.3.8 

MS 

Match Strings 

<match list> 

1 

R/I 

6.1.4 

VNEW 

New variables 

[# IS] 


R/I 

6.1.11 

GR 

Graphics 

< s ub- command s> 


R/I 

6.1.12 

SO 

Sound 

<vars> | <pntrs> I <consts> 

R/I 

6.1.13 

PA 

Paus ' 

<nexp> 


R/I 

6.1.14 

TAPE 

Cassette control 

0N| OFF 


R/I 

6.1.15 

TSYNC 

Cassette synch. 

<null> 


R/I 

6.1.16 

READ 

I/O input 

<device> [ <var> ] 

3 

R/I 

6.1.37 

WRITE 

I/O output 

<device><texp> 

3 

R/I 

6.1.17 

CLOSE 

I/O complete 

<dev ice> 

3 

R/I 

6.1.17 

POS 

Position cursor 

<column><row> 


R/I 

6.1.18 

TRACE 

Trace execution 

ON | OFF 


R/I 

6.1.19 

DUMP 

Dump string vars 

<null> 


R/I 

6.1.20 

LOAD 

Load stored prog 

<device> 

3 

R/I 

6.3.21 

CALL 

Call assy program 

<nexp> 


R/I 

6.1.22 

LIST 

List stored prog 

<line#Xline#> 

2 

I 

6.2.1 

RUN 

Run stored prog 

<nul 1> 


I 

6.2.2 

SAVE 

Save stored prog 

<device><# ><#> 

2 

I 

6.2.3 

DOS 

Go disk utility 

<null> 

\ 

I 

6.2.4 

NEW 

Clear stored prog 

<nul 1> 

I 

6.2.5 

AUTO 

Auto-number input 

<1 ine# Xl ine# > 

2 

I 

6.2.6 

REN 

Program renumber 

<1 ine# Xl ine# > 

2 

I 

6.2.7 


Notes : 

1. The entire operand is evaluated as a text expression before 
command scanning of the parameters commences. 

2. Line numbers must be numeric constants only. 

3. lo£. (x. td&nsl of a. 
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The Graphics command sub-commands and operand syntax are shown b ° low - 


PEN 

QUIT 

GOTO 

DRAWTO 

FILLTO 

TURN TO 

GO 

DRAW 

FILL 

TURN 

CLEAR 


Pen color select 
Quit graphics mode 
Move cursor 
Draw line 
Draw line & fill 

Rotate 

Move cursor relative 
Draw line relative 
Fill line relative 
Rotate relative 
Clear screen 


RED I YELLOW I BLUE I ERASE | UP 
<x-coord> <y-coord> 

<x-coord><y-coord> 
<x-coord> <y-coord> 

<angle> 

<units> 

<uni ts> 

<uni ts> 

<angle> 


J C ‘-Swv. | (.< Csvva 

('Wv'o.Lir^- Ctso— <^T) < SoijC-svuu-tt^Ji 
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This appendix lists the Atari 4B0/80B system I/O error codes 
within ?he context in which they will be seen in Atari PILOT. 

Not all of the the system codes a ^® p ^®OT environment, 
some of them cannot occur within the PILOT environment. 

] 30 A non-existent device was specified. 

j c i i -i urt tf command with the same device 

131 A READ command followed a WRliE commai 

specif ied . 

135 A WRITE command followed a READ command with the same device 
specified. 

136 End of file condition. 

138 Device timeout; device doesn’t respond. (Note 1) 

139 Device NAK. (Note 1) 

140 Serial bus framing error. (Note 1) 

141 Screen cursor out of range (READ from or WRITE to 

142 Serial bus data frame overrun. (Note 1) 

143 Serial bus data frame checksum error. (Note 1) 

144 Device DONE error. (Note 1) 

145 Disk read after write compare error. (Note 1) 

146 Function not implemented for device (e.g. OUT:K). 

147 Insufficient RAM for operating the graphics screen. 

160 Disk drive # error. 

161 Too many concurrent disk files being accessed. 

162 Disk is full (no free sectors). 

163 Fatal system data I/O error. 

164 File # mismatch. (Note 1) 

165 Disk file naming error. 

167 Disk file locked. 


169 


Disk directory full (64 files) 


170 Disk file not found in directory. 


seldom be seen. 
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Appendix D — SIGNIFICANT MEMORY ADDRESSES 


This appendix provides the addresses of many of the Atari PILOT 
interpreter's internal variables, buffers, pointers and stacks. 
The knowledgeable user may be able to play some interesting 
tricks using these elements. For more information regarding the 
implementation of the Atari PILOT interpreter see the ATARI 
PILOT INTERNAL SPECIFICATION. 



Address 

decimal 

Address 

hex 

Length 

(bytes) 

Content 

144 

0090 

1 

Use stack index (1 byte pointer) . 

1 291 

050B 

16 

Use stack. 

1 307 

053B 

52 

Numeric variables (#A to #Z). 

I 82 

00B6 

2 

Var iable/pointer address. 

184 

0 0B8 

2 

Numeric item value. 

1 47 

0093 

2 

Expression value. 

174 

0 0AE 

2 

Pointer to start of program area. 

176 

00B0 

2 

Pointer to end of program area. 

1 32 

0084 

2/ . 

Pointer to next statement to 
execute (run mode) . 

178 

00B2 

2 

Pointer to start of string list. 

I 80 

0 0B4 

2 

Pointer to end of string list. 

1 90 

00BE 

4 * 

String NAME pointer. 

194 

0 0C 2 

4* 

String VALUE pointer. 

140 

0 08C 

4* 

Pointer to text expression buffer 

1 399 

0577 

255 

Text expression evaluation buffer 

1 28 

0080 

4* 

Pointer to command input buffer. 

1654 

0676 

123 

Command line input buffer. 

I 36 

0088 

4* 

Pointer to accept buffer. 

1280 

0500 

1 

I/O error disable flag. 

228 

0 0E4 

I 

I/O status byte. 

1 373 

0 55D 

1 

User AUX1 byte. 

1 374 

055E 

I 

User AUX2 byte. 

1 363 

0553 

3 

Graphics pen color. 

1 nn7 

4>fcFl 


S'V&jpl'Uc«> aCfe-tiA. lA/lodfi. 

1772' 

06F2. 


Spare bytes for user. 


The 4-byte pointers flagged with above have an internal 

format as shown on the following page: 


1 3S* <t>*87 


screen 

SC.KUL'K. \e,ifer l UUVfc\\i>\«_wt(s_ ^ 
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Atari PILOT interpreter 4-byte pointer format: 


7 0 

+ + 

I base I 

+- - + 

| pointer I 

+ V 

I start offset | 

+ + 

I end offset ( + 1)1 

+ + 


byte 0 
1 
2 
3 


Atari PILOT interpreter string list & program list format: 


+ 

I 

+ 


+ 

I 


+ 

I 

+ 


1st 

i tern 

2nd 

i tern 


last 

i tern 


| low memory address. 
4- 

l 

+ 

I 

i 

+ 

| high memory address 
+ 


Where each item has the format shown below: 


7 

H — — 

| item size 
+ - 
I 

+ 

| name size 

H — — — — 

I name value 

I 

= 1 to 254 

| bytes 

I 

H — 

| data size 

+ 

I data value 

I 

= 0 to 254 

I bytes 

I 

+ 



The item size is also used as 
a relative pointer to the next 
item in the list. 

(Always = 2 for program list). 

(Contains the binary line 
number in inverted form for 
the program list, and ATASCII 
characters for the string list). 


Contains ATASCII characters. 
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Appendix E -- MODE CHANGE BEHAVIORS 


This appendix describes the cha 
that may occur as the result of 


Event 

Quit 

Close 


Graphics 

RD/WRT 


mode? 

files? 

POWER-UP 

YES 

Note 1 

RESET & 



WARMSTART 



from DOS 

YES 

Note 1 

BREAK 

NO 

Note 2 

I/O ERROR 

NO 

Note 3 

RUN: 

NO 

YES 

U: (immed) 

NO 

NO 

j: (immed) 

NO 

NO 


K[Q — — "* — 

— YES- 

E: 

NO 

No te 4 

Program off 



end 

NO 

NO 

Run-time err 

NO 

NO 

GR : QUIT 

YES 

NO 

NEW: 

NO 

YES 

VN EW : $ 

NO 

YES 

VNEW: # 

NO 

NO 

VNEW: 

NO 

YES 

LOAD (immed) 

NO 

NO 

LOAD (run) 

NO 

NO 

Line insert/ 



delete 

NO 

NO 


nqes in the 

PILOT env 

i ronment 

various events of consequence 

Clear 

Clear 

Clear 

Vars? 

Program? 

screen? 

YES 

YES 

YES 

NO 

NO 

YES 

NO 

NO 

NO 

NO 

NO 

NO 

YES 

NO 

YES 

NO 

NO 

NO 

NO 

NO 

NO 

% T — - 

xm 

NQ 

— NO 

NO 

fvt/ 

NO 

NO 

NO 

NO 

NO 

NO 

NO 

NO 

NO 

NO 

YES 

YES 

YES 

NO 

$ only 

NO 

NO 

# only 

NO 

NO 

YES 

NO 

NO 

NO 

NO 

NO 

NO 

YES 

NO 

NO 

NO 

NO 


Note 1 
closed 
lost . 


-- All READ/WRITE files are 
in some cases, information 


terminated, but not formally 
(or complete files) may be 


Note 2 -- If the BREAK causes an I/O error 
file will be closed; if the BREAK does not 

then the file will not be closed. 


then the affected 
cause an I/O error. 


Note 3 


Only the file causing 


the error will be closed. 


Note 4 — YES if Use stack is empty, else NO 
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Event 

Cl ear 

Cl ear 

Clear 

Stop 

Cl ear 


accept 

Match 

Use 

Cassette 

sounds? 


buffer? 

flag? 

stack? 

motor ? 


POWER-UP 

YES 

YES 

YES 

YES 

YES 

RESET & 






WARM3TART 






from DOS 

YES 

YES 

NO 

YES 

YES 

BREAK 

NO 

NO 

NO 

YES 

YES 

I/O ERROR 

NO 

NO 

NO 

YES 

YES 

RUN: 

YES 

YES 

YES 

NO 

Note 1 

U: (immed) 

NO 

NO 

YES 

NO 

NO 

J: (immed) 

NO 

NO 

XT A 

NO 

iii rv~ 

NO 

yp e 

NO 

YES 

E-;~- end 

E: -fimmed) ^ 

— NO — 

NO 

— _ 

NO 

INU 

NO 

IDO 

Note 2 

X U * 

Note 2 

Program off 






end 

NO 

NO 

NO 

YES 

YES 

Run-time err 

NO 

NO 

NO 

YES 

YES 

GRiQUIT 

NO 

NO 

NO 

NO 

-no- yes 

NEW: 

NO 

NO 

YES 

NO 

Note 1 

VNEW : $ 

NO 

NO 

NO 

NO 

*joy£s 

VNEW:# 

NO 

NO 

NO 

NO 

Note 1 

VNEW: 

NO 

NO 

NO 

NO 

Ndt-e i yes 

LOAD (immed) 

NO 

NO 

Screes 

.no- yes 

.no- yes 

LOAD (run) 

NO 

NO 

YES 

ue-yes 

no yes 

Line insert/ 






delete 

NO 

NO 

YES 

NO 

NO 

Note 1 -- Does not clear sound 

selects , 

but does zero 

the numeric 

variables, which may 

make sounds silent. 



Note 2 -- YES if the 

Use stack 

is empty. 

else NO. 

\ 

The Trace flag is cleared only 

by TRACE 

OFF, power-up 

and RESET. 
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Appendix F -- ATARI CONTROLLER CHARACTERISTICS 

This appendix describes the manner in which the Atari 
controllers are sensed in Atari PILOT. 

?S ddle u :«-J here are up to ei 9 ht P^dles that can be sensed (%P0 
through %P7) ; each paddle yields a numeric value from 0 (for 

full counterclockwise rotation) to 227 (for full clockwise 
rotation) . 

'T There are up to four joysticks that can be sensed 
( % J 0 through %J3); each joystick yields a numeric result, 
depending upon the joystick position, as shown below: 


1 0 


2 


Triggers -- There are twelve triggers that can be sensed, eight 
paddle triggers (%TC through %T7) and four joystick triggers 
(%T8 through %T11); each trigger yields a value of 0 if not 
pressed or 1 if pressed. 

Lightpen -- A single lightpen may be sensed using the three special 
variables shown below: 

%H = lightpen horizontal position. 

% V = lightpen vertical position. 

%L = lightpen trigger (0 if not pressed, 1 if pressed). 

Any executed reference to one of the lightpen special variables 
will change the background (ERASE) color from black to light 

gray so as to allow the lightpen to operate at all regions of 
the screen. 

See Appendix G, item 7 for more information regarding the Atari 
lightpen . 
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Appendix G -- APPLICATION NOTES 


This document contains a collection of techniques and tricks 
that enable the user to perform functions that mi|ht not 
otherwise appear possible in “an PILOT. This is y 
comprehensive, but merely represents the solutions to som. 

problems that have been encountered. 


]. DISPLAYING THE CONTENT OF THE ACCEPT BUFFER 

TO display the content of the Accept buffer while 
mode, enter the following commands: 


in immediate 


MS: , 
DUMP 

The string 
content of 
unaltered . 


named ’$RIGHT< will have as a value the 
the Accept buffer and the Accept bu 


then 

will 


cur rent 
remain 


2. SAVING AND RESTORING THE ACCEPT BUFFER 

The Accept buffer may be saved and restored 
shown below: 


using the techniques 


*S AVEACCEPT 
MS: , 

C :$ASA7E=$RIGHT 
E: 


♦RESTORE ACCEPT 
A : =$ASAVE 
E: 


3. USING STRING ARRAYS 

While string arrays are not a bv^lln^str inglndUe^tiSn? 

St r ing^may f be^created'whic^ar^the^conca tenat ion of text and 

numbers and then if those strings are used as the « 

other strings, the function of string arrays will P of space 

One advantage for many applications is that the amoun 

allocated corresponds to the tota of “ 1 5 ® h Sn to the 

individual string stored to the a “ay- length- a definite 

advantage to * sparse array and variable length string 

applications . 


C : #S=5 

C : $NAME=STRING#S 
C : $$NAME=DATA PORTION 


The result of this sequence will be 
named ' STRING5 1 which will have the 


to croduce 3 string 
value 'DATA PORTION'. 


4. CONVERSION OF TEXT/NUMERIC DATA 

The Compute statement allows the data type as 
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below: 

r • <numer ic var i able>=<numer i c expression> 

C : <str ing var iable>-<text exytw 

t-vDG assignments shown 
The Accept statement allows the dat YP 

below : 

A : Cnumer ic 

A : <str ing var iable>-<text expt 

i- the four combinations of data 

between the two statements, the 
assignments shown below are possible: 


numeric to numeric 


c :#A=#B+1 
A : #A=#B 

TEXT TO TEXT 


source may be a numeric or constant, 

source may be numeric variable or 


r-SABC=YOUR NAME IS $N AME 
A : $ABC=YOUR NAME IS $N AME 


NUMERIC TO TEXT 

C : $VALUE=#X 
A : $ VALUE=# X 

TEXT TO NUMERIC 
A : #V = $VALUE 


. nnriship or constant 

source may be numeric variable constant 

source may be numeric vanaDie 

source contains a number as part 


5. NUMERIC/TEXT STACK SIMULATION 


^ numeric stack may be simulated by concatenating ^ujer ic ^ata 

to a string; depending upon either a LIF0 stac k 

to the beginning or the ena ul 
or FIFO buffer may be simulated. 

. p LIF0 stack simulation. Shown below are 
First we shall examine a L!FO s racx pus h an d pop 

three routines which perform init ( i , s " the simulated 

operations , using the string , named STAuK^ d3ta . period 

stack, and the numeric J^minate each stack entry, an exclamation 
will be used to terminate e .. k fot overflow detection 

point (•!■) will terminate- the si tael « fo uhen 3n at tempt is 

raaniVoP aatl ^mVn^stack or when the stack 
nuprf lows . 


★INITSTACK 
C : $STACK= I 
E: 

★ PUSH 

A : $STACK=#D . $STACK 
M : ! 

TN: STACK OVERFLOW. 
E: 
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*POP 

A : =$STACK 
MS: . 

TN: STACK UNDERFLOW. 
EN: 

A : #D=$LEFT 
C : $STACK=$RIGHT 

E: 


Next we shall examine a FIFO buffer simulation. The very: same 
techniques ate used here as for the LIFO example althoughthe 

subroutine and string names have ee ^ c n a t ha *WRITEFIFO 

differences are to be found between the *PUSH and the 

routines . 


*F1F0INIT 
C :$F1F0=! 
E: 


*WRITEF I FO 
A : =$FIFO 
MS: I 

CY : $FIFO=$LEFT#D . ! 
MY: ! 

TN : FIFO OVERFLOW. 
E: 


*READFIFO 
A=$FIFO 
MS: . 

TN : FIFO EMPTY. 
EN: 

A : #D=$LEFT 
C : $FIFO=$RIGHT 

E: 


p , f c _ r /o j- 1, 3 of non - numeric data may be handled in a simila 

manner'usin^string names or string data in^ce^f^he^errc 

the 1 strin^value 3 static once^ssigned , assuming that the name 
is shorter than the value, because the stack may then contain 
more entries before overflow occurs than when the string value 

are stacked. 

6. TOKENIZING A TEXT STRING 

. ct-rina mav be broken up into words (tokens) by a left to 

^aht seaming technique as shown below; the sample program will 
“?ept SS1I text, and then print out the individual words within 
the text (in single quotation marks). 


T:Please enter 
A: 

*LOOP 
MS : >_ 

EN: 

T: ' $LEFT 1 
A : = $RIGHT 
J :*LOOP 


a line of text. 


[ skip over 1st blank and match on 2nd. 
[ nothing left — all done. 

[ this is the next word. 

[ put the remainder to the acc. buff .. 
[ ... and continue scanning. 
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A text string may be broken up into single characters (excluding 
blanks) by a scanning technique shown below: 


T-.Please enter a 
A: 

MS: , 

A : =$RIGHT! 

♦LOOP 

MS:>>, 

EN: 

MS : $RIGHT 
C :$SAVE=$MATCH 
A : =$LEFT 
MS : 

T: ' $LEF'I' ' 

A : =$S AVE 
J :*LOOP 


line of text. 

[ get accept buffer to $RIGHT, ... 

[ ... append ! to end & store back. 

f skip over blank and char of interest, 
f nothing left — all done. 

[ $LEFT will contain blank and single char. 

[ save remainder as we will clobber acc. ^ 

[ accept buffer contains blank, char, blank. 

[ skip 1st blank & match on 2nd (last) blank. 
( aha! here is our character. 

[ restore the accept buffer ... 

[ ... and continue scanning. 


7. READING THE LIGHTPEN 

A subroutine to read the lightpen and convert 
PILOT graphics coordinates is shown below. 


the position to 


♦GETPT J ( %L=0 ) : *GETPT 

C : #H=%H 

C : #X=#H-1 52 

C ( #H<6 ) : #X=#X+227 

C : #Y=64-%V 

E: 
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8. SIN/COS VALUES 

Th<=> SINE and COSINE functions can be derived from the graphics 
screen capabilites, as shown below: 

T : Please enter an angle (in degrees) . 

A : # A 

GR : GOTO 0,0; TURNTO #A ; DRAW 10000 
T : Si ne ( %A ) = %X E-4. 

T:Cosine(%A) = %Y E-4. 

E: 


S. PEEK/POKE MAGIC 


The following examples show interesting things that can be 
performed using PILOT pointers. 


pen color 


\ 


The pen color can be 
command by storing a 


altered without using the GR : PEN x xx 
byte value to location 1363 (decimal). 


C :@Bl 363-0 
C :@Bl 363=1 
C : @B1 363=2 
C:@B1363=3 
C :@B1363 = 4 
C : @B1 36 3 = ?\4 
C :@B1 363=@B1 363+l\4 


is equivalent to GR:PEN ERASE. 

«• ~ » " GR:PEN RED. 

.. •• " gr-.pen YELLOW. 

.. » " GR : PEN BLUE. 

.. " " GR : PEN UP. 

is a random pen color selection. 

selects the next color. 
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reassigning color registers 

The actual colors assigned to each pen color name may be altered 
by poking a byte value to one of four color registers. 


C :@B71 2=xx 
C :@B708=xx 
C :@B709=xx 
C :@B710=xx 


changes the color assigned 


II 

II 

II 


II 

II 

11 


II 

II 

II 


II 

H 

II 


to ERASE. 

" RED. 

YELLOW. 
BLUE. 


91 


II 


The form of the color register byte is shown below: 


7 6 5 4 3 2 1 0 
+-+-+-+-+-+-+-+-+ 
| color I lum 1 0 1 
+-+-+-+-+-+-+-+-+ 


Where: color 

0 = 

1 = 

2 = 

3 = 

4 = 

5 = 

6 = 

7 = 

8 = 

9 « 

10 « 
11 - 
12 = 

1 3 < 

14 * 

15 


gray 

light orange 

orange 

red orange 

pink 

purple 

purple-blue 

blue 

blue 

light blue 
turquoise 
r i aen-bl ue 
c reen 

yellow-green 
orange-green 
light orange 


lum 

0 = minimum luminance 

1 = I 

2 = I 

3 = (increasing 

4 = luminance) 

5 = I 

6 = I 

7 = maximum luminance 


A color register value can be calculated as shown below. 

C:@B708 = (#C * 16) + (#L * 2) [ #C = color, #L = lum. 

finding free space for pointer work 

Th° unused RAM memory within the Atari PILOT environment is 
defined by two addresses: 1) the lowest free memory address is 
contained in the word at location 176 (decimal) and 2) the 
highest free memory address is contained in the word at location 
178 (decimal). Note that Atari PILOT adds stored program 
statements to the low memory region (causing the address at 
location 176 to increase) and adds named strings to the high 
memory region (causing the address at 178 to decrease) Since a 
PILOT program can add to the string storage r equi cements, but 
can't alter the program size (except through the use of LOAD), 
the low memory region is the safer area from which to start 

allocating . 


C : #L=@1 7 6 
C : #H = @1 7 8 


[ free memory low address to #L. 
( free memory high address to #H 


sfcop execution from within a Use routin'? 
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If it is desired to immediately stop execution from within a Use 
routine, the following sequence may be employed: 

C :0B1 44=0 
E: 

Storing a zero to byte 144 (decimal) has the effect of clearing 
the Use stack, thus making the E: that follows appear to be an 
outer level Exit. 

changing the screen margins 

The left and right text screen margins may be altered as shown 
below : 

C:@B82=0 left margin = 0. 

C :@B83=39 right margin = 39. 

The default values for the left and right margins are 2 and 39, 
respectively, but other values may be set at the user's 
discretion. 

10. READING THE KEYBOARD 

The console keyboard may be read directly using the program 
shown below: 

♦WAIT J (@B764=255) : *WAIT [ wait for a keystrike. 

C:#C = @B7 6 4 [ save the keycode. 

C : @B76 4 = 255 [ clear the code just read. 

The keycode read by this program is not ATASCII and cannot be 
readily converted ;:o ATASCII by an algorithmic process. If 
conversion is required, a lookup technique (using the Match 
command or a pointer) would do the trick. The keycodes may be 
obtained empirically or by referencing the ATARI PERSONAL 
COMPUTER SYSTEM O.S. USER'S MANUAL or the ATARI PERSONAL 
COMPUTER SYSTEM HARDWARE MANUAL. 

11. GENERATING KEYWORDS IN TEXT EXPRESSIONS 

Some difficulty may be experienced in generating certain text 
literals within an operand that is evaluated as a text 
expression, for example in a Type command. There are a couple 
of tricks that will allow the user to generate just about 
anything, based upon the fact that all "keywords" in PILOT are 
two or more characters in length (except for '?' which is not 
evaluated in a text expression anyway). l WsuiK.e.4 1 C. ' Ue 

Technique #1 — The first technique is to insert into the 
keyword an innocuous set of screen control characters, such as 
Ccursor up> followed by Ccursor down>. 

T:#4^A Will put ' # A ' to the screen. 

T:$-HNAME Will put ' $NAME ' to the screen. 

Technique #2 -- The second technique is to create one or more 
named strings that contain portions of the keywords to be 
generated. These strings may then be concatenated with text 
literals or other named strings to generate the keywords. 
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C : $A=A 
T:#$A 


Will put ' #A ' to the screen. 


Technique #3 — String variables names will be generated 
automatically just by being undefined. 


T : $NAME 


Will put ' $NAME ' to the screen, if the 
variable has never been defined. 


12. WRITING LARGE CHARACTERS TO THE SCREEN 

S - 

Usinq facilities explained in section 6.1.17, 
PERSONAL COMPUTER SYSTEM 'USER ' S MANUAL, large 
written to the screen as shown below: 


and in the 
characters may be 


C :@Bl 37 3 = 16 
C :@B1 374 = 2 
WRITE :S, LARGE 
WRITE:S, large 
T:Press return 
A: 

E : 


[ split screen select to AUXl. 
{ screen mode 2 to AUX2. 

LETTERS, 
letters . 
to continue. 



13. READING A DISK DIRECTORY 

- 


Using facilities explained in s 
PERSONAL COMPUTER SYSTEM USER'S 
read as shown below: 


C : $D IR=D : * . * [ 
C : @Bl 37 3 = 2 [ 
*LOOP 

READ : $DIR $FNAME [ 
J (@B228=136) :*DONE [ 
T : $FNAME t 
J : *LOOP 

*DONE CLOSE :$DIR 
E: 


ction 6.1.17, and in the 
MANUAL, a disk directory may be 


wildcards to read all filenames, 
read director select to AUXl. 

read directory information, 
exit loop on EOF status, 
type directory information. 


14. USING ATARI CONTROLLERS WITH PILOT GRAPHICS 

Th^ Atari contollers can be used to interactively control 
graphics presentations as shown by the progrm segment shown 
below. The example assumes that a pair of Paddle Conao 
inserted into the first controller port. 


l s 


*LOOP 

GR(%T0) : CLEAR 
C :@B708=%Pl 


[ clear screen on paddle 0 trigger 
[ reassign color of PEN RED. 


<graphics program body> 

PA : %P0/1 03 t variable delay. 

J : *LOOP 
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